home *** CD-ROM | disk | FTP | other *** search
/ Aminet 52 / Aminet 52 (2002)(GTI - Schatztruhe)[!][Dec 2002].iso / Aminet / util / libs / ttengine.lha / ttengine-4.1 / Developer / autodocs / ttengine.doc
Text File  |  2002-09-29  |  24KB  |  630 lines
  1. TABLE OF CONTENTS
  2.  
  3. ttrender.library/background
  4. ttrender.library/font_database
  5. ttrender.library/TT_CloseFont
  6. ttrender.library/TT_GetAttrsA
  7. ttrender.library/TT_OpenFontA
  8. ttrender.library/TT_SetAttrsA
  9. ttrender.library/TT_SetFont
  10. ttrender.library/TT_Text
  11. ttrender.library/TT_TextExtent
  12. ttrender.library/TT_TextFit
  13. ttrender.library/TT_TextLength
  14. ttrender.library/background                       ttrender.library/background
  15.  
  16.  
  17.    PURPOSE
  18.  
  19.    The library is fast, AmigaOS friendly TrueType render engine. It has
  20.    nothing to do with Amiga outline font system. This system has a lot of
  21.    limitations which make it useless for high speed and quality text output.
  22.    If someone wants an integration of TrueType with AmigaOS bullet.library
  23.    like outline font system, should consider using ttf.library. This library
  24.    opens TrueType font by itself and renders high quality glyphs directly
  25.    into any RastPort.
  26.  
  27.    FREETYPE2 BASED
  28.  
  29.    The render engine of the library is based on FreeType2 project
  30.    (http://www.freetype.org). This version of ttrender.library uses 2.0.9
  31.    FreeType build.
  32.  
  33.    REQUIREMENTS
  34.  
  35.    - OS 3.0+.
  36.    - 68020 or better processor.
  37.    - for antialiased output graphics board with at least 15-bit screenmode
  38.      and RTG system: CyberGraphX 3.x+ or Picasso96 2.x+.
  39.  
  40.    FEATURES
  41.  
  42.    The library expands FreeType functionality making usage of TrueType fonts
  43.    easy and comfortable. Below you can find key features:
  44.  
  45.    - renders whole strings (not single glyphs) with kerning.
  46.    - antialiasing to any (not neccesarily uniform color) background.
  47.    - system compatible output to any (including planar) RastPort.
  48.    - supports JAM1. JAM2, INVERSVID, COMPLEMENT RastPort modes.
  49.    - supports 8-bit to Unicode mapping with "ENV:ttfcodepage" table
  50.      compatible with ttf.library.
  51.    - allows for direct 16-bit Unicode string rendering.
  52.    - easy to use, taglist based API almost identical to graphics.library
  53.      font API.
  54.    - efficient system-wide glyph cache system.
  55.  
  56.    CACHE SYSTEM
  57.  
  58.    The library uses my own (not that experimental FreeType one) cache system
  59.    speeding up strings rendering alot. The cache is system-wide, it means it
  60.    is common to every application using ttrender.library. Only used glyphs of
  61.    given font face are cached. If the library encounters cache miss, missing
  62.    glyph is loaded and rasterized on the fly. Cache system is totally
  63.    transparent to the library user, so there are no cache functions in the
  64.    library API. Cache uses one single Exec memory pool avoiding memory
  65.    fragmentation.
  66.  
  67. ttrender.library/font_database                 ttrender.library/font_database
  68.  
  69.    GENERAL INFORMATION
  70.  
  71.    'ttengine.database' is a plain text file (placed in 'ENV:' directory)
  72.    containing informations about TrueType fonts available in the system.
  73.    There is no tool (yet) to automatically generate it, the database have to
  74.    be written by hand. Every line contains one keyword followed by parameter
  75.    value. Name and value can be separated by space(s) or equality sign,
  76.    exactly the same as shell command parameters (to say more - database is
  77.    parsed by the same ReadArgs() system call as shell command parameters
  78.    are). Parameter values containing spaces should be quoted. Here are some
  79.    examples:
  80.  
  81.    FAMILY Tahoma
  82.    FAMILY=Times
  83.    FAMILY = "Times New Roman"
  84.    FAMILY "Weird Font"
  85.  
  86.    KEYWORDS
  87.  
  88.    FAMILY - defines the name used for font opening. All variants of the font
  89.    (italic, bold, black, heavy, light, demi etc.) will have the same family
  90.    name. Family names (and aliases described below) are case insensitive.
  91.  
  92.    ALIAS - defines another name for the same family. It generally has three
  93.    purposes:
  94.  
  95.    1. Similar names for the same font, like "Times", "TimesNewRoman" and
  96.    "Times New Roman".
  97.  
  98.    2. One replacement font for some very similar ones, for example
  99.    "Helvetica" and "Switzerland" can be aliased to "Arial".
  100.  
  101.    3. Generic names like "default", "serif", "sans-serif", "monospaced". An
  102.    application can request generic name without specific family name, or
  103.    generic font can be used as a fallback if given name can't be found in
  104.    the database. For example you can alias "monospaced" to "Courier", and an
  105.    application (be it CSS compatible HTML viewer) can request
  106.    'LucidaConsole, monospaced'. If there is no LucidaConsole font in the
  107.    system, Courier will be used. The same way you can alias any font to any
  108.    other, for example Times to Arial, this makes not much sense however.
  109.    'default' font can be used as a last resort.
  110.  
  111.    FILE - defines single TrueType font file and its attributes, which are:
  112.      FILE itself - defines a path to the font file. Font files can be placed
  113.        anywhere in the filesystem(s). There is no default value for the
  114.        attribute, it must be given explicitly.
  115.      WEIGHT - defines font weight in Cascading Style Sheets manner, where 0
  116.        means the lightest and 999 means the heaviest weight. 400 is typical
  117.        value for normal weight, 700 for bold. Default value is 400 (normal).
  118.      STYLE - "regular" or "italic" for italic and oblique faces. Default
  119.        value is "regular".
  120.      SMOOTHSMALL - controls antialiasing of small sizes. Any sizes smaller or
  121.        equal to SMOOTHSMALL will be antialiased. Note: can be overriden by
  122.        application. Default value is 9.
  123.      SMOOTHBIG - controls antialiasing of big sizes. Any sizes bigger or
  124.        equal to SMOOTHBIG will be antialiased. Note: can be overriden by
  125.        application. Default value is 18.
  126.  
  127.      Every FILE is automatically added to the nearest FAMILY defined above
  128.      in the database file. Every ALIAS or FILE placed before the first
  129.      FAMILY is rejected quietly.
  130.  
  131.    COMMENTS
  132.  
  133.    You can place any full-line comments in the file starting a line with
  134.    hash or semicolon. End-line comments are not supported.
  135.  
  136. ttrender.library/TT_CloseFont                   ttrender.library/TT_CloseFont
  137.  
  138.    NAME
  139.        TT_CloseFont -- Closes TrueType font. (V4)
  140.  
  141.    SYNOPSIS
  142.        TT_CloseFont (font)
  143.                      A0
  144.  
  145.        VOID TT_CloseFont (APTR);
  146.  
  147.    FUNCTION
  148.        Closes font opened by TT_OpenFontA()
  149.  
  150.    INPUTS
  151.        font - the result of TT_OpenFontA(). Can be NULL, no action is taken
  152.            in the case.
  153.  
  154.    RESULT
  155.        none
  156.  
  157.    NOTES
  158.  
  159.    BUGS
  160.  
  161.    SEE ALSO
  162.        TT_OpenFontA()
  163.  
  164. ttrender.library/TT_GetAttrsA                   ttrender.library/TT_GetAttrsA
  165.  
  166.    NAME
  167.        TT_GetAttrsA -- Gets current font and render engine attributes (V4).
  168.  
  169.    SYNOPSIS
  170.        count = TT_GetAttrsA (rastport, taglist)
  171.                              A1        A0
  172.  
  173.        ULONG TT_GetAttrsA (struct RastPort*, struct TagItem*);
  174.  
  175.        count = TT_GetAttrs (rastport, Tag1, ...)
  176.  
  177.        ULONG TT_GetAttrs (struct RastPort*, Tag, ...);
  178.  
  179.    FUNCTION
  180.        Gets current font or render engine attributes for given RastPort. The
  181.        value of every attribute is written to an ULONG pointed by ti_Data
  182.        field of the TagItem. Here is a list of attributes:
  183.  
  184.        TT_Antialias - Current state of an antialias switch (on, off or
  185.           auto).
  186.  
  187.        TT_Ascender - This is a distance (in pixels) between the baseline
  188.          and top elements of the font (typically these elements are accents
  189.          of capital letters). NOTE: many shareware TT fonts have wrong ascen-
  190.          der value.
  191.  
  192.        TT_Descender - This is a distance (in pixels) between the baseline
  193.          and bottom elements of the font (typically in letters 'p', 'q', 'g'
  194.          etc.). NOTE: many shareware TT fonts have wrong descender value.
  195.          Descender value is typically negative (as bottom elements usually
  196.          are placed below the baseline).
  197.  
  198.        TT_FontName - full font name as found in the font file. Pointer to a
  199.          NULL-terminated string is written. This string is localized if the
  200.          font file contains names in different languages. Language
  201.          precedence is loaded from "Preferred languages" table of
  202.          locale.library.
  203.  
  204.        TT_FamilyName - font family name as found in the font file. Pointer
  205.          to a NULL-terminated string is written. This string is localized if
  206.          the font file contains names in different languages. Language
  207.          precedence is loaded from "Preferred languages" table of
  208.          locale.library.
  209.  
  210.        TT_SubfamilyName - font subfamily name (typically describing font
  211.          variant like "italic" or "bold") as found in the font file. Pointer
  212.          to a NULL-terminated string is written. This string is localized if
  213.          the font file contains names in different languages. Language
  214.          precedence is loaded from "Preferred languages" table of
  215.          locale.library.
  216.  
  217.        TT_Transparency - returns actual transparency setting.
  218.  
  219.        NOTE: TTFA_Ascender and TTFA_Descender are guarranted to fulfill
  220.        following formula: ascender - descender = font height.
  221.  
  222.    INPUTS
  223.        rastport - attributes associated with this RastPort will be returned.
  224.        taglist - the list of attributes.
  225.  
  226.    RESULT
  227.        counter - the count of recognized tags.
  228.  
  229.    NOTES
  230.        Data returned are valid only until TT_CloseFont() call.
  231.  
  232.    BUGS
  233.  
  234.    SEE ALSO
  235.        TT_OpenFontA(), TT_SetAttrsA()
  236.  
  237. ttrender.library/TT_OpenFontA                   ttrender.library/TT_OpenFontA
  238.  
  239.    NAME
  240.        TT_OpenFontA -- Opens TrueType font. (V4)
  241.  
  242.    SYNOPSIS
  243.        font = TT_OpenFontA (taglist)
  244.                                A0
  245.  
  246.        APTR TT_OpenFontA (struct TagItem*);
  247.  
  248.        font = TT_OpenFont (Tag1, ...)
  249.  
  250.        APTR TT_OpenFont (Tag, ...);
  251.  
  252.    FUNCTION
  253.        Opens a TrueType font preparing it to use with any RastPort. Font may
  254.        be specified directly as a path to "*.ttf" file, or indirectly via
  255.        set of attributes, database search will be performed for this set and
  256.        best matching font will be opened. It is graphics.library OpenFont()
  257.        counterpart but taglist is used instead TextAttr structure.
  258.  
  259.    INPUTS
  260.        taglist - a list of tags containing requested font attributes.
  261.               Following tags are recognized:
  262.          TT_FontFile - this tag is a pointer to string containing a full
  263.               path to TrueType font file to be opened. This tag allows for
  264.               overriding database search and match. That means
  265.               TT_FamilyTable, TT_FontStyle and TT_FontWeight are ignored if
  266.               TT_FontFile is specified. Useful for opening application
  267.               specific fonts, containing for example musical notes or some
  268.               other kind of symbols. This tag has no default value.
  269.          TT_FamilyTable - NULL-terminated table of pointers to font family
  270.               names from the most desired to the last resort fallback. It is
  271.               intended for easy implementing things like HTML 'FONT FACE'
  272.               attribute. You can use real family names here, as well as
  273.               generic names: 'serif', 'sans-serif', 'monospaced', 'cursive',
  274.               'fantasy', and 'default', especially useful as a fallbacks.
  275.               Family names are case insensitive.
  276.               The default value for the tag is {"default", NULL};
  277.          TT_FontSize - font size in pixels defined as the distance between
  278.               baselines of two following text lines. The default value for
  279.               this tag is 14 pixels.
  280.          TT_FontStyle - there are two styles defined:
  281.               TT_FontStyle_Regular (default),
  282.               TT_FontStyle_Italic.
  283.          TT_FontWeight - defined with Cascading Style Sheets manner as a
  284.               number from 0 (the lightest face) to 999 (the heaviest face).
  285.               You can use TT_FontWeight_Normal (equal to 400) and
  286.               TT_FontWeight_Bold (equal to 700) shortcuts.
  287.               TT_FontWeight_Normal is the default value.
  288.  
  289.  
  290.    RESULT
  291.        success - font pointer (for use with TT_SetFont() and TT_CloseFont())
  292.                  if the font has been opened successfully, NULL
  293.                  otherwise. This function can fail for four reasons:
  294.                  1. There is no matching face in the database (NOTE: even
  295.                     'default' can fail if not defined in the database!)
  296.                  2. File not found or malformed.
  297.                  3. Zero font size.
  298.                  4. No memory for requested (too big?) size.
  299.  
  300.    NOTES
  301.  
  302.    BUGS
  303.  
  304.    SEE ALSO
  305.        TT_SetFont(), TT_CloseFont(), font_database
  306.  
  307. ttrender.library/TT_SetAttrsA                   ttrender.library/TT_SetAttrsA
  308.  
  309.    NAME
  310.        TT_SetAttrsA -- Sets rendering engine and font attributes. (V4)
  311.  
  312.    SYNOPSIS
  313.        count = TT_SetAttrsA (rastport, taglist)
  314.                              A1        A0
  315.  
  316.        ULONG TT_SetAttrsA (struct RastPort*, struct TagItem*);
  317.  
  318.        count = TT_SetAttrs (rastport, Tag1, ...)
  319.  
  320.        ULONG TT_SetAttrs (struct RastPort*, Tag, ...);
  321.  
  322.    FUNCTION
  323.        Sets render engine settings for given RastPort. Every following
  324.        TrutType render and metrics calls for this RastPort will use these
  325.        settings. Here is a list of attributes:
  326.  
  327.        TT_ColorMap - (struct ColorMap*) - ColorMap used to convert pen
  328.          number to RGB color value.
  329.  
  330.        TT_Screen - (struct Screen*) - useful shortcut for TTA_ColorMap,
  331.          automatically sets screen ColorMap.
  332.  
  333.        TT_Window - (struct Window*) - useful shortcut for TTA_ColorMap,
  334.          automatically sets window ColorMap.
  335.  
  336.        TT_Antialias - (BOOL) - controls antialiasing (on, off or
  337.          automatic):
  338.          TTA_Antialias_Off - turns antialias off
  339.          TTA_Antialias_On - turns antialias on
  340.          TTA_Antialias_Auto (default) - antialias state depends on font
  341.            size. Typically sizes of 9 or less pixels are antialiased, sizes
  342.            from 10 to 19 pixels are not antialiased, sizes of 20 of more
  343.            pixels are antialiased. These settings can be changed in the font
  344.            database separately for every font face.
  345.  
  346.        TT_Encoding - selects font encoding table to be used:
  347.          TT_Encoding_Default - loads encoding table from "ENV:ttfcodepage"
  348.            file, compatible with ttf.library. If no such file is found,
  349.            ISO-8859-1 encoding (Amiga default) is used.
  350.          TT_Encoding_Unicode - strings are interpreted as tables of 16-bit
  351.            Unicode characters.
  352.          TT_Encoding_ISO8859_1 - ISO-8859-1 (Western Europe).
  353.          TT_Encoding_ISO8859_2 - ISO-8859-2 (Eastern and Central Europe).
  354.  
  355.        TT_Transparency - Allows for rendering transparent text (the
  356.          background shines through the text). 0 value means no transparency
  357.          (this is the default), 255 is maximum transparency.
  358.  
  359.    INPUTS
  360.        rastport - attributes will be set for this RastPort.
  361.        taglist - the list of attributes.
  362.  
  363.    RESULT
  364.        counter - the count of recognized tags.
  365.  
  366.    NOTES
  367.  
  368.    BUGS
  369.  
  370.    SEE ALSO
  371.        TT_OpenFontA(), TT_Text(), TT_GetAttrs()
  372.  
  373. ttrender.library/TT_SetFont                       ttrender.library/TT_SetFont
  374.  
  375.    NAME
  376.        TT_SetFont -- Sets TrueType font for a RastPort. (V4)
  377.  
  378.    SYNOPSIS
  379.        TT_SetFont (rastport, font)
  380.                    A1        A0
  381.  
  382.        VOID TT_SetFont (struct RastPort*, APTR);
  383.  
  384.    FUNCTION
  385.        Sets a font previously opened with TT_OpenFontA() for use with given
  386.        RastPort. All further calls of text rendering or metrics function for
  387.        this RastPort will use font set.
  388.  
  389.    INPUTS
  390.        rastport - The font will be set for this RastPort.
  391.        font - Pointer returned by TT_OpenFontA(). May be NULL, function
  392.            returns immediately in the case.
  393.  
  394.    RESULT
  395.        none
  396.  
  397.    EXAMPLE
  398.        /* use two fonts to render in one RastPort */
  399.  
  400.        APTR times, arial;
  401.  
  402.        times = TT_OpenFont(
  403.           TT_FamilyTable, (ULONG){"Times", "serif", "default", NULL},
  404.           TT_FontSize, 26,
  405.        TAG_END);
  406.  
  407.        arial = TT_OpenFont(
  408.           TT_FamilyTable, (ULONG){"Arial", "sans-serif", "default", NULL},
  409.           TT_FontSize, 22,
  410.           TT_FontWeight, TT_FontWeight_Bold,
  411.        TAG_END);
  412.  
  413.        if (times && arial)
  414.          {
  415.            SetAPen(win->RPort, 1);
  416.            SetDrMd(win->RPort, JAM1);
  417.            Move(win->RPort, 100, 100);
  418.            TT_SetAttrs(win->RPort, TTA_Window, win, TAG_END);
  419.  
  420.            TT_SetFont(win->RPort, times);
  421.            TT_Text(win->RPort, "Times 26 points", 15);
  422.            TT_SetFont(win->RPort, arial);
  423.            TT_Text(win->RPort, "Arial 22 points", 15);
  424.          }
  425.        if (arial) TT_CloseFont(arial);
  426.        if (times) TT_CloseFont(times);
  427.  
  428.    NOTES
  429.      Function can fail silently if:
  430.      1. RastPort pointer is NULL.
  431.      2. Font pointer is NULL.
  432.      3. Font pointer is not found on opened fonts list (it means the pointer
  433.         was not obtained as a result of TT_OpenFontA() call.
  434.  
  435.    BUGS
  436.  
  437.    SEE ALSO
  438.        TT_OpenFontA(), TT_SetAttrsA(), TT_CloseFont()
  439.  
  440. ttrender.library/TT_Text                             ttrender.library/TT_Text
  441.  
  442.    NAME
  443.        TT_Text -- Renders string into RastPort. (V4)
  444.  
  445.    SYNOPSIS
  446.        TT_Text (rastport, string, count)
  447.                 A1        A0      D0
  448.  
  449.        VOID TT_Text (struct RastPort*, APTR, ULONG);
  450.  
  451.    FUNCTION
  452.        Renders the string using current ttrender.library settings, and
  453.        current RastPort settings (pen, drawmode). String is rendered at
  454.        current RastPort (x, y) position, where 'y' means position of font
  455.        baseline. String is converted to Unicode according to
  456.        current (set by TT_SetAttrs()) encoding table.
  457.  
  458.    INPUTS
  459.        rastport - Target RastPort for rendering.
  460.        string - String to render to (need not to be NULL terminated).
  461.        count - How many characters to render (note that NULL code will
  462.            be rendered as well).
  463.  
  464.    RESULT
  465.        none
  466.  
  467.    EXAMPLE
  468.        /* write a text with pen 1 and transp. background at (100, 100) */
  469.        /* rendering is done to a system window                         */
  470.  
  471.        SetAPen(win->RPort, 1);
  472.        SetDrMd(win->RPort, JAM1);
  473.        Move(win->RPort, 100, 100);
  474.        TT_SetAttrs(win->RPort, TTA_Window, win, TAG_END);
  475.        TT_Text(win->RPort, "some text", 9);
  476.  
  477.    NOTES
  478.  
  479.    BUGS
  480.  
  481.    SEE ALSO
  482.        TT_OpenFontA(), TT_SetAttrsA()
  483.  
  484. ttrender.library/TT_TextExtent                 ttrender.library/TT_TextExtent
  485.  
  486.    NAME
  487.        TT_TextExtent -- Determine raster extent of text data. (V4)
  488.  
  489.    SYNOPSIS
  490.        TT_TextExtent (rastport, text, count, extent)
  491.                       A1        A0    D0:16  A2
  492.  
  493.        VOID TT_TextExtent (struct RastPort*, APTR, WORD,
  494.            struct TextExtent*);
  495.  
  496.    FUNCTION
  497.        Computes dimensions and coordinates of smallest rectangle containing
  498.        on the whole given text rendered with current settings. TextExtent
  499.        structure fields have following meaning:
  500.  
  501.        te_Width - Horizontal advance of RastPort pen position. The same as
  502.            TT_TextLength() call result.
  503.        te_Height - Just current font height.
  504.        te_Extent.MinX - The horizontal distance from text start point to the
  505.            leftmost pixel rendered. May be negative, it means that some
  506.            pixels will be plotted before the start point.
  507.        te_Extent.MaxX - The horizontal distance from text start point to the
  508.            rightmost pixel rendered.
  509.        te_Extent.MinY - The vertical distance from text start point to the
  510.            topmost pixel rendered. Always negative, do not neccesarily equal
  511.            to -TTFA_Ascender.
  512.        te_Extent.MaxY - The vertical distance from text start point to the
  513.            lowermost pixel rendered. Typically positive if anything is to be
  514.            drawn below the baseline.
  515.  
  516.    INPUTS
  517.        rastport - this rastport settings (font, size, style etc.) will be
  518.            used for calculations.
  519.        text - a string (not neccesarily NULL-terminated) to compute the
  520.            rectangle for.
  521.        count - length of the string in characters.
  522.        extent - pointer to TextExtent structure - it will be filled with
  523.            data.
  524.  
  525.    RESULT
  526.        No retrurn value. TextExtent structure is filled with data.
  527.  
  528.    NOTES
  529.        This function is almost identical to graphics.library/TextExtent().
  530.        It even receives parameters in the same registers.
  531.  
  532.        Do not assume neither horizontal extents sum up to te_Width, nor
  533.        vertical ones sum up to font height.
  534.  
  535.    BUGS
  536.  
  537.    SEE ALSO
  538.        TT_OpenFontA(), graphics.library/TextExtent()
  539.  
  540. ttrender.library/TT_TextFit                       ttrender.library/TT_TextFit
  541.  
  542.    NAME
  543.        TT_TextFit -- Count characters that will fit in a given extent. (V4)
  544.  
  545.    SYNOPSIS
  546.        characters = TT_TextFit (rastport, string, count, extent,
  547.                                 A1        A0      D0:16  A2
  548.            constr_extent, direction, width, height)
  549.            A3             D1         D2     D3
  550.  
  551.        ULONG TT_TextFit (struct RastPort*, APTR, UWORD, struct TextExtent*,
  552.            struct TextExtent*, WORD, UWORD, UWORD);
  553.  
  554.    FUNCTION
  555.        Computes how many characters of given NULL-terminated string rendered
  556.        with current settings will fit into given extent. Also calculates an
  557.        extent for this fitting part of the string. Function can fit from the
  558.        beginning of the string to the right, or from the end of the string
  559.        to the left. If 'constr_extent' is non NULL, string is fitted only
  560.        against it, constraining 'width' and 'height' are ignored.
  561.  
  562.    INPUTS
  563.        rastport - calculations will be performed using this rastport
  564.            settings (font, size, styles etc.).
  565.        string - A string (not neccesarily NULL-terminated) to fit.
  566.        count - string lenght in characters.
  567.        extent - Pointer to TextExtent structure - it will be filled with
  568.            dimensions of fitted part of the string. May be filled with all
  569.            zeros if no fit is possible at all (e.g. height is to small).
  570.        constr_extent - Pointer to already filled TextExtent structure. Part
  571.            of the string will fit into this extent. It is not modified by
  572.            function. May be NULL, 'width' and 'height' will be used as
  573.            constraints.
  574.        direction - When equal to 1 string will be fitted starting from it's
  575.            beginning to the rigth. When equal to -1, string will be fitted
  576.            starting from it's end to the left.
  577.        width - If 'constr_extent' is NULL, the string width will be compared
  578.            with this parameter. Ignored otherwise.
  579.        height - If 'constr_extent' is NULL, the string height will be
  580.            compared with this parameter. Ignored otherwise.
  581.  
  582.    RESULT
  583.        characters - the length of fitting string part. May be zero if no fit
  584.            found.
  585.  
  586.    NOTES
  587.        This function is almost identical to graphics.library/TextFit().
  588.        It even receives parameters in the same registers.
  589.  
  590.        Do not assume neither horizontal extents sum up to te_Width, nor
  591.        vertical ones sum up to font height (in returned extent).
  592.  
  593.    BUGS
  594.  
  595.    SEE ALSO
  596.        TT_OpenFontA(), graphics.library/TextFit()
  597.  
  598. ttrender.library/TT_TextLength                 ttrender.library/TT_TextLength
  599.  
  600.    NAME
  601.        TT_TextLength -- Gets string length in pixels (V4).
  602.  
  603.    SYNOPSIS
  604.        length = TT_TextLength(rastport, string, count)
  605.                               A1        A0      D0
  606.  
  607.        ULONG TT_TextLength (struct RastPort*, APTR, ULONG);
  608.  
  609.    FUNCTION
  610.        Calculates the pixel width of given string written with current font.
  611.        Takes kerning into account. String will be mapped to Unicode using
  612.        current encoding.
  613.  
  614.    INPUTS
  615.        rastport - render engine and font settings for this RastPort will be
  616.            used for calculations.
  617.        string - the length of this string will be calculated.
  618.        count - the string lenght in characters.
  619.  
  620.    RESULT
  621.        length - the length of the string in pixels.
  622.  
  623.    NOTES
  624.  
  625.    BUGS
  626.  
  627.    SEE ALSO
  628.        TT_Text(), TT_OpenFontA()
  629.  
  630.